<!DOCTYPE html>
<html class="Content">
<head>
    <title>xUnit.js: Assertions</title>
    <link type="text/css" rel="Stylesheet" href="../../Style/documentation.css" />
</head>
<body>
    <h1>Assertions</h1>
    <p>
        Assertions are the life-blood of unit tests, and this is no different in xUnit.js. Common Assertions are provided via the static <strong>Assert</strong> class. Custom assertions
        can be created by throwing instances of <strong>xUnit.js.Model.AssertError(</strong>[<em>message</em>]<strong>)</strong>. 
    </p>
    <p>    
        Borrowing again from the concepts of <a href="http://xunit.codeplex.com/">xUnit.net</a>,
        xUnit.js prefers structured assertions to free-form messages. Messages are reserved for the most ambiguous assertions, <strong>Assert.Fail(reason)</strong>, 
        <strong>Assert.True(value,message)</strong>, and <strong>Assert.False(value,message)</strong>.
    </p>
    <p>
        The following assertions are included by default:
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>AssignableFrom</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that the instance or class specified by <em>actual</em> is a valid instance, interface, or sub-class of the function <em>expected</em>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Contains</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
        Verifies that the <em>expected</em> Object or Array contains the <em>actual</em> value. For objects, this represents the value of a key, for arrays, the value of an index position.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>DoesNotContain</strong>(expected,actual);        
        </span>
        <span class="Block Indent-2">
            Verifies that the <em>expected</em> Object or Array does <strong>not</strong> contain the <em>actual</em> value. For objects, this represents the value of a key, for arrays, the value of an index position.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>DoesNotThrow</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that the function delegate <em>actual</em> does <strong>not</strong> throw an Error of any sort.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Empty</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is an empty Array, Function, Error, String, or Object. Booleans, Dates, and Numbers can never be considered "empty", and will always throw an Error.
            Arrays and Strings are considered empty when they have a length of zero. Errors are considered empty when they have no message. Functions are considered empty when they consist of
            only whitespace or comments. Objects are considered empty when they have no public properties.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Equal</strong>(expected,actual); 
        </span>
        <span class="Block Indent-2">
            Verifies that <em>expected</em> and <em>actual</em> are trivially equal. "Trivially equal" means that in the case of Booleans, Numbers, and Strings, the values are equivalent, but not 
            necessarily the same reference; in the case of Arrays, Dates, Errors, and Objects, it means that the public properties or index positions are also trivially equal.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Fail</strong>(reason);
        </span>
        <span class="Block Indent-2">
            Throws an <strong>xUnit.js.Model.AssertError</strong>, with an optional <em>reason</em>. 100% of the time, every time. That's it. No tricks. Keep this out of production code. 
            In fact, the only reason to use this method is to verify that a piece of (test) code was never called.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>False</strong>(actual,message);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> evaluates to false. This is a strict evaluation, only Boolean values of false will pass. Typical falsey values, such as 0, '', null, undefined will throw 
            an <strong>xUnit.js.Model.AssertError</strong>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>InRange</strong>(actual,low,high,comparer);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is greater than or equal to <em>low</em>, and less than or equal to <em>high</em>. If <em>comparer</em> is specified, verifies that <em>comparer</em>
            returns a value below or equal to zero when comparing <em>low</em> to <em>actual</em> and a value below or equal to zero when comparing <em>actual</em> to <em>high</em>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotEmpty</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is not an empty Array, Function, Error, String, or Object. Booleans, Dates, and Numbers can never be considered "empty", and will always pass this test.
            Arrays and Strings are considered not empty when they have a length greater than zero. Errors are considered not empty when they have an error message. Functions are considered not 
            empty when they consist of more than whitespace and comments. Objects are considered not empty when they have at least one public property.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotEqual</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>expected</em> and <em>actual</em> are trivially note equal. "Trivially not equal" means that in the case of Booleans, Numbers, and Strings, the values are not 
            equivalent, and not the same reference; in the case of Arrays, Dates, Errors, and Objects, it means that the public properties or index positions are also trivially not equal.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotInRange</strong>(actual,low,high,comparer);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is less than <em>low</em>, or greater than <em>high</em>. If <em>comparer</em> is specified, verifies that <em>comparer</em>
            returns a value greater than zero when comparing <em>low</em> to <em>actual</em> and a value greater than zero when comparing <em>actual</em> to <em>high</em>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotNull</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is not exactly equal to <em>null</em>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotSame</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>expected</em> and <em>actual</em> are <strong>not</strong> precisely equal. In the case of Booleans, Numbers, and Strings, this means <em>value</em> 
            inequivalence. In the case of Arrays, Dates, Errors, Functions, and Objects, this means <em>reference</em>, or <em>instance</em> inequivalence.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotType</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is not of the <em>expected</em> type. This means that the object <em>actual</em> is neither an instance of <em>expected</em>, nor a sub-class thereof. 
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>NotUndefined</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is not "undefined", as reported by the <em>typeof</em> keyword.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Null</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is exactly equal to <em>null</em>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Same</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>expected</em> and <em>actual</em> are precisely equal. In the case of Booleans, Numbers, and Strings, this means <em>value</em> equivalence. In the case of 
            Arrays, Dates, Errors, Functions, and Objects, this means <em>reference</em>, or <em>instance</em> equivalence.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Throws</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that the function delegate <em>actual</em> throws an Error of the <em>expected</em> type.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>True</strong>(actual,message);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> evaluates to true. This is a strict evaluation, only Boolean values of true will pass. Typical truthy values, such as 1, 'string', [], and {} will throw 
            an <strong>xUnit.js.Model.AssertError</strong>.
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Type</strong>(expected,actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is of the <em>expected</em> type. This means that the object <em>actual</em> is an instance of <em>expected</em>, or a sub-class thereof. 
        </span>
    </p>
    <p class="Double">
        <span class="Code">
Assert.<strong>Undefined</strong>(actual);
        </span>
        <span class="Block Indent-2">
            Verifies that <em>actual</em> is "undefined", as reported by the <em>typeof</em> keyword.
        </span>
    </p>

</body>
</html>